.\" Copyright (c) 2008-2018 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd November 17, 2007
.Dt AG_CURSOR 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.4
.Sh NAME
.Nm AG_Cursor
.Nd agar cursor operations
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
#include <agar/gui/cursors.h>
.Ed
.Sh DESCRIPTION
The
.Nm
interface provides Agar widgets with control over the shape of the mouse cursor.
Specific cursors can be associated with specific rectangular areas in a widget's
local coordinate system.
.Sh WIDGET INTERFACE
.nr nS 1
.Ft "AG_CursorArea *"
.Fn AG_MapCursor "AG_Widget *wid" "AG_Rect r" "AG_Cursor *c"
.Pp
.Ft "AG_CursorArea *"
.Fn AG_MapStockCursor "AG_Widget *wid" "AG_Rect r" "int cursorName"
.Pp
.Ft "void"
.Fn AG_SetCursor "AG_Widget *wid" "AG_CursorArea **cursorArea" "AG_Rect r" "AG_Cursor *c"
.Pp
.Ft "void"
.Fn AG_SetStockCursor "AG_Widget *wid" "AG_CursorArea **cursorArea" "AG_Rect r" "int cursorName"
.Pp
.Ft "void"
.Fn AG_UnmapCursor "AG_Widget *wid" "AG_CursorArea *cursorArea"
.Pp
.nr nS 0
The
.Fn AG_MapCursor
function configures a new cursor-change area described by the rectangle
.Fa r
(in pixels, relative to the parent window's local coordinate system).
When the mouse is moved within this rectangle, Agar will set the specified
cursor
.Fa c .
The return value of
.Xr AG_CursorNew 3
or
.Xr AG_CursorFromXPM 3
will typically be used.
The allocated cursor will be freed automatically by Agar when the window is
detached.
.Pp
.Fn AG_MapStockCursor
sets up a cursor-change area associated with a stock Agar cursor.
See
.Sx STOCK CURSORS
for the list of acceptable
.Fa cursorName
arguments.
Since cursors are associated with window or driver-specific resources,
.Fn AG_MapCursor
will fail if the widget is not attached to any parent window.
However,
.Fn AG_MapStockCursor
may be called by an unattached widget, and as a special case, Agar will
defer the operation until the widget is attached to a window.
.Pp
.Fn AG_MapCursor
and
.Fn AG_MapStockCursor
both return a pointer to the
.Ft AG_CursorArea
structure describing the cursor-change area, or NULL if an error has occurred
(without setting an error message).
.Pp
The
.Fn AG_SetCursor
and
.Fn AG_SetStockCursor
routines provide an alternate interface to
.Fn AG_MapCursor
and
.Fn AG_MapStockCursor .
If the pointer at
.Fa cursorArea
is NULL, a new cursor area is mapped and returned into it.
Otherwise, the rectangle of the existing cursor area is updated from
.Fa r .
If the given cursor doesn't exist (or doesn't exist yet, as for an
.Xr AG_Window 3
in the process of being setup), then NULL is returned into
.Fa cursorArea .
.Pp
.Fn AG_UnmapCursor
removes the specified cursor-change area.
If the mouse happens to be currently in this area, the cursor will be
reverted immediately to the default.
.Sh INTERFACE
.nr nS 1
.Ft "AG_Cursor *"
.Fn AG_CursorNew "AG_Driver *drv" "Uint w" "Uint h" "const Uint8 *data" "const Uint8 *mask" "int xHot" "int yHot"
.Pp
.Ft "AG_Cursor *"
.Fn AG_CursorFromXPM "AG_Driver *drv" "char *xpmData[]" "int xHot" "int yHot"
.Pp
.Ft void
.Fn AG_CursorFree "AG_Driver *drv" "AG_Cursor *cursor"
.Pp
.Ft "AG_Cursor *"
.Fn AG_GetStockCursor "AG_Driver *drv" "int name"
.Pp
.Ft "AG_Cursor *"
.Fn AG_GetActiveCursor "AG_Driver *drv"
.Pp
.Ft void
.Fn AG_ShowCursor "AG_Driver *drv"
.Pp
.Ft void
.Fn AG_HideCursor "AG_Driver *drv"
.Pp
.Ft int
.Fn AG_CursorIsVisible "AG_Driver *drv"
.Pp
.nr nS 0
.Fn AG_CursorNew
registers a new hardware cursor with the underlying graphics driver.
The cursor's pixels are determined from bytes in
.Fa data
(1 = black, 0 = white)
and
.Fa mask
(1 = opaque, 0 = transparent).
The
.Fa w
and
.Fa h
arguments specify the dimensions of the surface in pixels.
The tip of the cursor is located at coordinates
.Fa xHot
and
.Fa yHot .
.Pp
.Fn AG_CursorFromXPM
creates a cursor from the contents of an XPM file.
.Pp
.Fn AG_CursorFree
releases all resources allocated by a cursor.
.Pp
.Fn AG_GetStockCursor
returns a pointer to a built-in cursor (see
.Sx STOCK CURSORS
for a list).
.Pp
.Fn AG_GetActiveCursor
returns a pointer to the currently active cursor.
.Pp
.Fn AG_ShowCursor
and
.Fn AG_HideCursor
control the visibility of the active cursor.
.Fn AG_CursorIsVisible
returns 1 if the active cursor is visible, 0 otherwise.
.Sh STOCK CURSORS
As of this writing, Agar provides the following built-in cursors:
.Bd -literal
enum {
	AG_FILL_CURSOR,
	AG_ERASE_CURSOR,
	AG_PICK_CURSOR,
	AG_HRESIZE_CURSOR,
	AG_VRESIZE_CURSOR,
	AG_LRDIAG_CURSOR,
	AG_LLDIAG_CURSOR,
	AG_TEXT_CURSOR,
	AG_LAST_CURSOR
};
.Ed
.Sh STRUCTURE DATA
For the
.Ft AG_CursorArea
structure:
.Pp
.Bl -tag -compact -width "AG_Widget *wid "
.It Ft AG_Rect r
The
.Xr AG_Rect 3
area (relative to the parent window's coordinate system).
Widgets may modify this rectangle directly.
.It Ft AG_Cursor *c
The associated cursor (read-only).
.It Ft AG_Widget *wid
The widget responsible for the cursor (read-only).
.It Ft int stock
If set, the cursor is a stock Agar cursor (read-only).
.El
.Sh SEE ALSO
.Xr AG_Driver 3 ,
.Xr AG_Intro 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
An
.Nm
interface first appeared in Agar 1.0.
A more extensive API was introduced in Agar 1.4.
